…ect-time auto-install and self-activating daily sync (#159)

* feat(package): add voc-data-pull v0.1.0, auto-installed on VoC platform connect

Installer package that pulls raw voice-of-customer data - product reviews,
support conversations, and ad comments - from a connected platform into
standardized files in the org brain: one file per review/ticket/comment,
flat metadata header + body, untouched platform payload preserved in every
file (PDEC-9193, PR 1 of 2).

- skill/SKILL.md: the pull workflow - resolve the connection path
  (Pipedream OAuth via integrations proxy, stored secret via secure-fetch,
  Motion native for Meta ad comments), follow the platform recipe, write
  files under /agent/brain/data-sources/<platform>/. Hard boundaries:
  read-only against platforms, bounded pulls (12-month default, page caps),
  never write into /agent/brain/integrations/<source>/, author_contact
  nulled pending the PII policy call.
- skill/references/platform-recipes.md: per-platform endpoints, pagination,
  discovery steps, and unified-template field mappings with evidence
  levels. Judge.me/Gorgias/Intercom live-verified; Trustpilot/Yotpo
  doc-grounded pending first connects; Junip blocked on a dead key;
  Okendo/Stamped are secrets-path (no Pipedream app exists); Meta ad
  comments via motion meta creative-comments.
- skill/templates/: copyable review and support-conversation file skeletons
  (support shape follows the Ramy Brook Gorgias precedent:
  daily/<date>/ticket-<id>.md, metadata top, full conversation below).
- package.json manifest: one directory resource installing the skill to
  agent_skills/voc-data-pull; installPolicy auto so matching intent
  installs with no manual step, updatePolicy auto so recipe fixes roll out.
- package-index.json: first indexed package. Categories list one
  integration:<slug> per platform (judge_me, trustpilot, yotpo, junip,
  gorgias_oauth, intercom, okendo, stamped) because the VM reconciler
  matches literal connected slugs - no invented family category.
- scripts/validate-runneth-package-index.mjs: aligned with the current
  package-manager contract (package.json manifests, installPolicy,
  packageManagerVersion 1|2, manifest v2 tasks/workflows, backend-github
  sources). Same content as #152; whichever merges first rebases clean.
- Card files (use-case.json, README.md, marketing.md) included per repo
  structure; slug added to catalog excluded[] - not a public-site use case.

CI note: the fleet-approval gate fires (new auto-installable package) and
needs the runneth-fleet-change-approved label after core engineering
approval.

* refactor(voc-data-pull): move under packages/ per installer package convention

* fix(voc-data-pull): resolve review findings - id-keyed ticket paths, honest date-bound claims, PII disclosure, fleet-gate fingerprint

* fix(voc-data-pull): render metadata as fenced yaml block instead of frontmatter

* feat(voc-data-pull): human-readable file layout - headline, bold-label header, collapsed metadata; drop raw payloads

* feat(voc-data-pull): backend-github source + activation package instruction

Switch the index entry's package source to backend-github per repo package
conventions, so VM artifact fetches route through the backend cache instead
of raw GitHub (bump indexRevision to 2026-07-22-01).

Add a package_instruction resource (instructions/activation.md) that lands
in the agent's standing instructions on install: Runneth offers the first
pull when a covered VoC platform is connected and no data-sources pull
exists, runs the skill on request, and never starts a pull without user
confirmation. Install stages files only; this closes the awareness gap
without auto-running anything.

* fix(voc-data-pull): date window is the coverage contract - page cap is per-run batching, never a coverage limit

* feat(voc-data-pull): add Reddit - integration:reddit category, community_post source type, recipe + template

* feat(voc-data-pull): routine-based recurring sync via activation instruction

activation.md: routine absence triggers setup - creates voc-sync-<platform> (cron 0 6 * * *), kicks the backfill run, silent-success/delivered-failure delivery, Junip key gate; pulls never run in-conversation. SKILL.md: new Recurring sync runs section owns the incremental window (empty folder = trailing 12 months, else newest created_at minus 2 days, updated_at for tickets), multi-account iteration, disconnect no-op; dropped the confirm-before-starting gate. README updated to match.

* fix(voc-data-pull): review fixes - id-keyed contract, per-source write policy, routine routing

SKILL.md: the id-keyed filename contract now survives existing folder conventions (adopt surrounding layout, keep id-keyed names); explicit re-pull write policy per source type (reviews skip, tickets overwrite on fresher updated_at, comments/posts overwrite inside the pull window since engagement mutates); user pull requests route through the sync routine; description covers Reddit and community posts. activation.md: routine prompt defers run behavior to the skill's recurring-sync rules instead of restating it; first kick described as a sync run whose window the skill determines. README: drop the stale no-automatic-post-install-trigger gap, describe the header shape directly, point the platform list at the Step 1 table.

* fix(voc-data-pull): move output to data-sources/voc/<platform>/ with flat type-prefixed filenames

* feat(voc-data-pull): manual install policy, ask-only sync setup

installPolicy flips to manual - the team installs per VM (package intent add-optional voc-data-pull + package sync); updatePolicy stays auto so installed copies track main. Setup is strictly manually triggered: the recurring-sync procedure (routine-absence check, routine add with cron 0 6 * * *, first-run kick, Junip gate, never pull in-conversation) moves into SKILL.md and runs only when asked, directly or via an onboarding run - nothing happens just because a platform is connected. The activation instruction slims to a pointer stating the same. Once set up, the daily routine refreshes data on its own. Categories retained for a future auto-install flip.

…23 (naming decoder JSON, Field 9 four captures)

Reconciles parallel work authored against the pre-merge base:

- Field 4 writes an operational naming decoder to /agent/brain/meta/naming-decoder.json:
  typed positions (segment_filter / context_only / unique_id / metadata_do_not_filter)
  mapped to Meta query fields, LP-reference decode (RLP/LP/CAP, do-not-filter), and the
  _VALUE_ filter-translation rules. Field 4 stays the interpretation owner; the decoder
  is its appendix, referenced from account-context.md, not embedded
- Field 9 restructured around four captures: ranking metric, CPA target (commentary,
  not a filter), winner/cut criteria applied only to explicit winner/cut questions
  (spend floor, min days, optional tiers with the rank-then-classify rule), and the
  default reporting window; supersedes v1.21's mandatory always-ask spend-floor script
- Merged with the v1.22 product-name-placement additions and the Step 1 provisional
  decode handoff; playbook, README, Knoweth answer standard, skeleton, and validation
  updated to point at the decoder

Co-authored-by: Jose <jose@motionapp.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

…l referenced by the 2.4.0 install entry

Co-authored-by: Cursor <cursoragent@cursor.com>

…k-sources named, raw-VoC save exemption, Reddit full-window contract

…as ACB v1.24 + validation v1.5; README covers the validation step

Field 10 (reporting structure and marketing calendar) synthesizes from
Fields 4, 7, and 9 - no new Motion pull - with an auto-detected
calendar from the naming decoder's campaign-type and launch-date
positions (read from naming-decoder.json, never an assumed offset) and
four standard deck sections as a starting hypothesis. Scope rule:
Field 10 gates the deck, not validation - the question loop runs on
the nine required fields; no deck without a confirmed Field 10, and an
unconfirmed spec runs its two beats at deck time. Validation v1.5
pre-fills the deck build from the spec, leads the deck-first door with
it, and anchors starter questions 2 and 4 in the confirmed dimensions
and calendar. Jose's stale-base regressions (Creative Corpus paths,
missing product-name placement and tier rule) were discarded.

Also reconciles the README with Eric's operational intro: adds the
missing Meta Validation detail section, the validation step in the
install/run order, and the validation-is-the-catch relation bullet.

Co-authored-by: Cursor <cursoragent@cursor.com>

…ecipe list - unknown platforms pull live-adapted

An unknown VoC platform is never skipped. The skill's scope gate changes
from "is it on the covered list" to "is the data customer voice": any
reachable reviews/support/survey/community platform with no recipe resolves
its connection path like the others (proxy or secure-fetch with the
registry guide's auth shape) and pulls through a new no-recipe path in
Step 2 - find the listing endpoints from the live API and docs, discover
pagination from the response, map the real payload onto the unified
record, pull the raw data you find, and report "no recipe - live-adapted"
with the calls used so a recipe can be written from the run. A missing
recipe is never a reason to stop; skipped can only mean not reachable,
not VoC, or dead auth.

Priority stays with the known platforms: recipe'd platforms are handled
first, and a platform that has a recipe is always pulled through its
recipe, never freelanced. Hard boundaries (read-only, 12-month window,
id-keyed files, PII null) and the output contract apply identically to
no-recipe pulls. Sync setup and the key-auth gate cover no-recipe
platforms; post-install's reachability check and the README state the
scope rule; the recipes header points platforms without a section at the
no-recipe path.

…T-vs-WHY evidence split, ACB fill-in output schema + Field 10 wiring

Rolls up v2.8.0-2.9.0 (rebased over Eric's v2.7.0 auto-fire + 17-platform VoC push): creatives always render as a gallery with decoder-normalized names (Data-Query Guide contract, validation v1.6 loop rule, skill output); the ad-performance skill's trigger broadened from single-ad to ads in general with an Analyzing Across Ads section; ACB v1.26 adds the three-part required output schema for the fill-in presentation and wires Field 10 into the flow and saved file (Step 5, deck-spec section); golden rule 10 splits evidence - live metrics answer WHAT, Cacheth creative content and VoC answer WHY; audit cleanup (single-ad README label, stale workspace-setup intro).

Co-authored-by: Cursor <cursoragent@cursor.com>

…xes, changelogs relocated to repo-only CHANGELOG.md

- v2.9.1: WHAT-vs-WHY section trimmed to evidence homes + pairing principle
- v2.10.0: answering-posture guidance (judgment over rules) in the Data-Query Guide; validation v1.7 register corrections; ACB v1.27 answer-register note
- v2.11.0: validation v1.8 autosave/resume, MVCE-to-Knoweth handoff, Q4 rework with single-pool fallback; knoweth v1.1 gate-2 file-based VoC fallback; gallery mediaUrl warning
- v2.11.1: per-doc changelog histories moved out of staged docs into aligned-onboarding/CHANGELOG.md (maintainer-only, never staged to customer brains)

Co-authored-by: Cursor <cursoragent@cursor.com>

…tim manifest entries

…se gate

Co-authored-by: Cursor <cursoragent@cursor.com>

… on a human's yes

- new onboarding-walkthrough skill (v1.0) owns the fill-in presentation; fires on "Are you ready to begin your onboarding?"
- ACB package (v1.29) drops the output schema + Steps 2-5, becomes the pure data layer; v1.28 adds format-per-data and the Field 4 inline decoder table rule
- post-install autofills and persists silently, ends with the verbatim invitation
- account-context guard v2 offers the walkthrough; Creative Attributes scope confirmation silent inside post-install
- package.json + package-index.json synced to 2.13.0

Co-authored-by: Cursor <cursoragent@cursor.com>

…north-star" renamed to plain language

- post-install step 6 gains a literal contract: one status line per part + question count, verbatim skeleton, no findings or question text before the invitation (first 2.13.0 field run leaked both)
- ACB v1.30 / validation v1.9: "north-star" -> "primary conversion event" and "priority campaign(s)" in all customer-facing phrasing
- package.json + package-index.json synced to 2.13.1

Co-authored-by: Cursor <cursoragent@cursor.com>

…, raw github source

Rename aligned-onboarding to meta-and-voc-onboarding (id, folder, staged
paths, all docs; the immutable pre-cleanup tag keeps its name). Version
policy is now a simple integer bumped once per package update, starting
at 1, with the CHANGELOG collapsed to that entry. The index entry moves
to categories: [] and a raw github source. Docs replace bare
`integrations status` with `integrations status --app <slug>` sweeps and
fix the `n run --url` typo to `secure-fetch run --url`. The validator
matches the runtime contract: opaque non-empty versions, github-only
sources, empty categories allowed, fleet approval checked only on
pull_request events.

…tor update

…th indexing model

Verified against agent-builder origin/staging (motion.ts, cache/exporters.ts,
cache/storage.ts) before editing.

- Access check first: playbook Step 2 opens with one
  `motion cache status --workspace-id <workspaceId>` call; on error, record the
  blocker and stop — no retry loops against the data commands. Same status-first
  note in the command reference overview.
- Fix the naming-decoder export flow: `motion cache export-summaries` returns a
  ./workdir wrapper, not the JSONL corpus. Docs now read the Meta corpus path
  from `exportPaths.meta` (command output) or `.providers.meta.path` (wrapper
  file) and run `jq -r '.adNames[]?'` against that per-provider file. Old
  instructions ran jq against the wrapper and produced an empty name list.
  Every Step 2 command now carries an explicit `--workspace-id`.
- Narrow data-surface claims: export and search records carry ad metadata, copy,
  landing/media URLs, and summary sections only. Transcripts and glossary/AI
  tags live solely on the full record via `motion cache get-creative`; removed
  "all transcripts / glossary tags" claims and the glossary jq example on
  exports, and dropped the transcript-fragment claim from search.
- Consistent Knoweth<>Cacheth model everywhere: Knoweth indexes the summary
  artifacts Cacheth generates (identity, ad names, copy, summary text), never
  complete records. Replaces both the "surfaced through Knoweth" overclaim and
  the "NOT indexed by Knoweth" underclaim across the package.
- Frame Cacheth as a hydration layer behind the motion CLI, transparent to the
  agent.
- Correct storage claims: only the wrapper lands in ./workdir; per-provider
  export files live in Cacheth's own storage.

Deliberately unchanged: guards/meta-validation-gate.md and its byte-identical
copy in meta-validation-onboarding-package.md (guard blocks merge verbatim into
/agent/user.md; changing them is a guard-versioning decision).

Staging validation:
- Positive path (cache-enabled orgs): status check ran once before export; the
  agent resolved the real corpus from exportPaths.meta, ran jq against the
  per-provider JSONL (never the wrapper), and decoded naming systems from
  hundreds of real ad names. The old empty-list failure did not reproduce, and
  no output claimed transcripts or glossary tags from export/search.
- Negative path (org with the sandbox Motion cache disabled, exercised
  deliberately): the status-first gate behaved exactly as written — the agent
  ran `motion cache status` once, quoted the playbook rule ("record the
  blocker and stop this step — do not loop retries"), recorded the blocker in
  the account-context file, and never touched the data commands or drew a
  false "no ads" conclusion.

…ed by staging runs

Four fixes to the install-time sequence, each grounded in a staging test
observation:

- Step 1 names the sanctioned stored-secret probe: the secret store cannot be
  listed (runtime refuses Bash reads of /agent/.runtime/secrets; neither
  `secret` nor `secure-fetch` has a list command), so probe each platform's
  documented secret key and treat "secret not available" as not stored. Same
  note added to the voc-data-pull skill's availability-check paragraph.
- Step 4 names the Creative Attributes procedure path
  (meta/meta-creative-attributes-playbook.md, a brain document) so agents stop
  probing for a nonexistent creative-attributes skill directory.
- Step 5 now matches the account-context playbook it delegates to: the brain
  file is written in the playbook's saved-file format (prose reference
  document) and indexed in /agent/INDEX.md with the playbook's aliases at
  install time. The old step text demanded terse facts and deferred INDEX.md,
  contradicting the playbook; agents consistently sided with the playbook.
- Step 6 closes two report-leak gaps: decoder shape counts ("a 5-position
  decoder", "4 schemas detected") are explicitly decoder detail, and the
  status-only discipline extends to the progress narration around the report,
  not just the report body.

…VM path

The package manifest flattens the repo's meta/ folder into
/agent/brain/meta-and-voc-onboarding/, so the playbook lives at
meta-and-voc-onboarding/meta-creative-attributes-playbook.md on the VM. Step 4
now names that staged path and forbids improvising the Creative Attributes step
from live Motion pulls when the playbook cannot be read.

…ets mechanical

Staging runs followed the descriptive wording loosely: one agent concluded
'no stored secrets' from a refused directory read without running a single
key probe, and another appended the detected naming convention to the
readiness report's Creative Attributes bullet. Step 1 now requires a
secret-run probe per key-stored platform before the step is done and rules
out indirect checks explicitly. Step 6 now states the template bullets are
filled only at their angle-bracket slots, with the allowed states as the
only permitted extensions.

…ace and placeholder scope

Step 3 told installers to replace every literal <workspaceId> token without
saying which workspace is the target; a staging run anchored on a stale id
from removed guard blocks and stamped the guards for the wrong workspace,
and the 'every token' rule also collided with the knoweth-organize guard's
generic project:<workspaceId> lane syntax. The target is now defined as the
workspace this conversation's Motion commands resolve to, substitution is
scoped to the guard headers, and the lane syntax stays untouched alongside
the other placeholders.

…add-optional + sync

The package description (manifest and index entry, kept byte-identical) now names the
canonical install path: an agent runs `package intent add-optional meta-and-voc-onboarding`
followed by `package sync`. The README's intro paragraph and "Install and run order" step 1
said the install conversation stages files "with one `package install` call" - that is the
branch-testing command, not the indexed flow. Both now describe the intent + sync pair;
explicit `package install github:...` remains documented only as the branch/PR-testing
variant.

… install sweep

Readiness report (post-install step 6): the template itself mandated the count
leak every install reproduced ("autofilled <N> of 9 fields; <M> questions need a
human"). The Account Context Brain bullet is now status-only ("done - remaining
gaps wait for the walkthrough"), the version label is dropped from the header
line (installs hallucinated four different labels for one artifact), and the
no-findings rule is now a blanket no-numbers rule (no counts, tallies, sample
sizes, or version labels anywhere in the report or the narration around it)
with a literal wrong/right example.

PR-URL resolution (README branch testing): step 1 prescribed gh pr view, which
fails with a 409 on every VM (GitHub is never connected there). The step now
says so and gives the working path: curl the public pulls API and read
.head.ref - the same fallback agents discovered on their own.

Staged paths (README): the five per-doc "File: meta/<doc>.md" lines and the
knoweth doc pointer were repo source paths, but the manifest stages those docs
flat; on-VM agents resolving them hit ENOENT. Each now carries its staged
/agent/brain/meta-and-voc-onboarding/ path.

One workspace per sandbox (post-install + playbook): the playbook's
multi-workspace section prescribed per-workspace-slug brain paths that the
guards and post-install never supported, so a second-workspace install had to
improvise (observed on staging: hand-copied brain files and rewritten guard
headers, leaving the first workspace unreachable). Both docs now state the one
Meta workspace per sandbox contract: same-workspace sentinels mean the sequence
already ran; different-workspace sentinels mean stop and report - never rewrite
guard headers or copy brain files.

…he account-context playbook path

Both staging verification installs of the tightened readiness report produced
the same single deviation: a part that completed through a fallback rendered
as "done - <explanation>" (Cacheth disabled, decode pulled from ad names
instead). Step 6 now states that "done" is terminal - a part that completed
through a fallback or degraded path is still exactly "done", and the how
belongs in the brain file - and enumerates "blocked - <reason>" among the
allowed bullet states.

Step 5 referred to "the account-context playbook" without naming its file;
one install guessed account-context-playbook.md, hit ENOENT, and recovered
via ls. The step now carries the staged path.

…-meta-package

…llback ladder (package v2)

Cacheth stays first for creative attributes; the live motion meta insights
content flags become a failure-only fallback with code-verified semantics
(sandbox-level MOTION_CACHE_ENABLED, explicit disabled message). Cache-disabled
sandboxes no longer permanently gate validation, brain organize, or the naming
decode (validation gate v4, knoweth-organize guard v3, validation doc v1.11).
Metrics pulls stay lean and join cached content on creativeId. Adds the
agent-builder PRD for enforcing the fallback in the CLI.

Co-authored-by: Cursor <cursoragent@cursor.com>

Turn synced customer language into durable, evidence-backed insight that validation and future analysis can reuse without running the audit automatically.

Co-authored-by: Cursor <cursoragent@cursor.com>

…mmary in walkthrough

Fixes from the first real customer-VM install, folded into the workspace-scoped v2:

- Field-to-command map names the real ads-grain extraction keys (verified against
  agent-builder's response schemas): ad rows carry no adName/campaignName/adsetName;
  identity lives at `name` and in associatedObjectDetails, populated only with
  --include-associated-objects. Field 4 decodes from the Creative Attributes handoff
  or adnames grain; response-shape note added to the map and the Data-Query Guide;
  the playbook's cache-disabled decode fallback switches to adnames grain.
- ACB navigation: `## Field N` headings, contents section, read-by-section note.
- account-context.md file-metadata block gets an explicit YAML template
  (fields_confirmed, field_statuses, open_flags, naming_decoder).
- Onboarding walkthrough now proactively presents a per-integration Voice of
  Customer summary after the account-context questions, explains what the audit
  entails, and hands the person the manual trigger (workspace-scoped paths and
  voc-sync-<workspace>-* routine names).

Co-authored-by: Cursor <cursoragent@cursor.com>

…er voc/meta-ad-comments

…questions and pre-answers in batch (doc v1.13)

The validation loop now generates its question set from the confirmed account
context instead of a fixed list: parameterized baseline questions plus one
derived question per filterable naming-decoder dimension (>=3 creatives,
meaningful 7-day spend), a Field 9 winner/cut probe, and a Field 7
testing-pipeline question. Answers pre-fill in batch before any are shown -
one no-limit primary insights pull (totalCount checked), a testing-bucket
pull, a conditional lifetime pull for lifetime spend floors, and creative
content through the content-layer ladder - then the full Q&A presents
together under a fixed answer format contract (verbatim question, bullets,
table at 3+ comparisons, gallery with decoded names; Winner/Watch/Cut only
on the winner/cut question). validation.md tracks generated and confirmed
account-specific question counts. No guard changes.

Co-authored-by: Cursor <cursoragent@cursor.com>